#!/usr/bin/perl

#################
# DOCUMENTATION #
#################

=pod

=head1 NAME

Kisge

=head1 VERSION

0.2.0

=head1 DATE

20070407

=head1 SYNOPSIS

=over

=item kisge.pl --project ['name']

Print information about project 'name', or last project

=item kisge.pl [--project 'name'] file(s)

Parse in file(s) (Kismet xml & gps)

=item kisge.pl [--project 'name'] --report [options]

Produce a report for project (default: Google Earth KMZ)

=item kisge.pl [--project 'name'] --rollback [dtg]

Roll the project database back to an earlier time, or one commit previous

=back

=head1 OPTIONS

=over

=item -c|--color field

colorize the ap's based on field

=item -s|--sort field[,field[...]]

sort hierarchy by field(s)

=item -s|--sort field [-s|--sort field] [...]

"

=item -f|--filter field:operator:value:negate|file

filter certain ap's from the data, or file containing filters

=item -p|--path rrggbb|0

path color or disable

=item --[no]kmz

(don't) make kmz

=back

=head1 ARGUMENTS

=over

=item file

relative or absolute path and filename or fileglob

=item field

ap attribute (possibly derived)

=item operator

compares field values

=item value

whatever

=item negate

reverse filter logic

=item rrggbb

color

=item dtg

date/time in yyyymmdd[hh[mm[ss]]] format

=back

=head2 ARGUMENT VALUES

=over

=item field

=begin text

Original fields:
number     maxseenrate     packets-weak
type*      carrier*        packets-dupeiv
ssid       encryption      packets-total
bssid      packets-llc     data-size
channel*   packets-data
maxrate    packets-crypt

Derived fields:
encryption-general*
manufacturer*

*Color-able

=end text

=begin html

<h2>Original fields</h2>
<table border="1" cellspacing="0" cellpadding="5">
  <tr>
    <td>number<br />type<br />ssid<br />bssid<br />channel<br />maxrate</td>
    <td>maxseenrate<br />carrier<br />encryption<br />encryption-general<br />packets-llc<br />packets-data</td>
    <td>packets-crypt<br />packets-weak<br />packets-dupeiv<br />packets-total<br />data-size</td>
  </tr>
</table>
<h2>Derived fields</h2>
<table border="1" cellspacing="0" cellpadding="5">
  <tr>
    <td>encryption-general*<br />manufacturer*</td>
  </tr>
</table>
<h3>*Color-able</h3>

=end html

=item operator

=begin text

                        Numerical   Stringwise
Less than                  <            lt
Greater than               >            gt
Less than or equal         <=           le
Greater than or equal      >=           ge
Equal                      ==           eq
Not equal                  !=           ne
Contains                                =~
Starts with                             =^
Ends with                               =$

=end text

=begin html

<table border="1" cellspacing="0" cellpadding="5">
  <tr><th>&nbsp;</th><th>Numerical</th><th>Stringwise</th></tr>
  <tr><td>Less than</td><td>&lt;</td><td>lt</td></tr>
  <tr><td>Greater than</td><td>&gt;</td><td>gt</td></tr>
  <tr><td>Less than or equal</td><td>&lt;=</td><td>le</td></tr>
  <tr><td>Greater than or equal</td><td>&gt;=</td><td>ge</td></tr>
  <tr><td>Equal</td><td>==</td><td>eq</td></tr>
  <tr><td>Not equal</td><td>!=</td><td>ne</td></tr>
  <tr><td>Contains</td><td>&nbsp;</td><td>=~</td></tr>
  <tr><td>Starts with</td><td>&nbsp;</td><td>=^</td></tr>
  <tr><td>Ends with</td><td>&nbsp;</td><td>=$</td></tr>
</table>

=end html

=head1 DESCRIPTION

=head2 PURPOSE

Plot Kismet wardrive data in Google Earth

=head1 DEFINITIONS

=head2 Kisge

=over

=item 1.

A compound word derived from the prefix "Kis" taken from the wireless network analysis tool, "Kismet", plus "ge", an acronym for "Google Earth", the popular virtual globe program used for mapping geographic data.

=item 2.

New Kisge was the eighth moon of Chaasch in Sulorine Sector, with dense underbrush-covered wilderness. It was the Samuac homeworld. General Vanden Willard established Delta Base on the moon prior to the Battle of Yavin. Being remote, the moon escaped the attention of the Empire.  Source: The Wookiepedia, http://starwars.wikia.com/wiki/New_Kisge.

=back

=head2 KML

An XML-based file format used to display geographic data in an Earth browser, such as Google Earth. Source: http://earth.google.com/kml/.

=head2 KMZ

A KML file along with supporting files compressed in a ZIP archive. Share via any means. Open with Google Earth to view.

=head1 CREDIT

Thanks given to bdkowert for creation of "Fon Hotspot in 3D" at http://sketchup.google.com/3dwarehouse/details?mid=70a7ef9a4448b8c4968c653a293751af. More information is also available at: http://bdkowert.com/category/fon/.

=head1 SEE ALSO

=head2 PROJECT PAGE

http://code.google.com/p/kisge/

=head2 NEWSGROUPS

Announcements: http://groups.google.com/group/kisge-announce

=head1 AUTHOR

Hiro Nakamura <hiro[dot]nakamura[dot]kisge[at]gmail[dot]com>

=head1 COPYRIGHT

Copyright (C) 2007 by Hiro Nakamura

=head1 LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or

b) the Artistic License as published by Larry Wall, either version 2.0, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this Kit, in the file named "license/perlartistic.txt".  If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "license/gpl.txt"; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

=begin comment

DATA:
  input:
    kismet.xml
    kismet.gps
  middle:
    db:
      project (name, start, finish, creator, )
        file (name, start, finish, stats?, pstart, pfinish)
      ap (bssid, essid, other attrib..., box_gps)
        box (min_coord, max_coord)
        sig (ap, sig, coord)
          coord (type[sig|box|file], lat, lon, alt, )
  output:
    a:
      googleearth.kml   # main
      files/*.dae       # models
      files/*.bmp|png   # icons
    b:
      googleearth.kmz   # zipped a

CODE:
lib/Kisge.pm            # loads Kisge::*
lib/Kisge/Parser.pm     # (XML::SAX) Parses in kismet xml/gps files into Kisge db [parser use mods, setup code, filters, db inserts]
lib/Kisge/DB.pm         # (SQLite::DB, Class::DBI) Kisge's middle tier db functionality [db use mods, initialize empty db, handle parser inserts, reporter queries]
lib/Kisge/Reporter.pm   # (Class::DBI, XML::SAX::DBI?) Produce report from 
lib/Kisge/Model.pm      # () creates dae files and the kml to insert them [creates model object, three methods: $model->new('rrggbb'), $model->dae('filename'), $model->kml()]
lib/Kisge/Icon.pm       # (GD?) creates placemark icons and the kml to insert them [like model... $icon->new('rrggbb'), $icon->png('filename'), $icon->kml()]
kisge.pl                # Documentation, command line options
doc/kisge.*             # Gendoc documentation

=end comment

=cut

